<!DOCTYPE html>
<body>
<br>
This document describes how to use H2O's generated POJO models.

<!-- ============================================================ -->
<!-- ============================================================ -->
<br>
<hr>
<br>

<h1><u>About generated models</u></h1>
<p></p>
H2O-generated POJO models are intended to be easily embeddable in any Java environment.
The only compilation and runtime dependency for a generated model is the h2o-genmodel.jar
file produced as the build output of this package.

<p></p>
If you are just getting started, refer to the <a href="#quickstart">Quick start</a> section below first,
then look at the documentation for the <em>hex.genmodel.easy</em> package.

<p></p>
The following topics are covered here:

<ul>
    <li>* <a href="#quickstart">Quick start</a></li>
    <li>* <a href="#extracting">Extracting generated models from H2O</a></li>
    <li>* <a href="#usecases">Use cases</a></li>
</ul>

<!-- ============================================================ -->
<!-- ============================================================ -->
<br>
<hr>
<br>

<a name="quickstart"></a>
<h1><u>Quick start</u></h1>

<h3>Step 1 (in terminal window 1): Start H2O</h3>
<pre>
$ java -jar h2o.jar
</pre>

<h3>Step 2 (in a web browser): Build model</h3>

<ol>
<li>Go to <a href="http://localhost:54321" target="_blank">http://localhost:54321</a></li>
<li>Click "view example Flows" near the right edge of the screen. Refer to the following screenshot:</li>

    <img border="2" src="doc-files/view_example_flows.png">

<li>Click "GBM_Airlines_Classification.flow"</li>
<li>If a confirmation prompt appears, click "Load Notebook"</li>
<li>From the "Flow" menu, choose "Run all cells" </li>
<li>Scroll down and find the "Model" cell in the notebook.  Click the Download POJO button (shown in the following screenshot):</li>

    <img border="2" src="doc-files/download_pojo_button.png">
<li> NOTE: The instructions below assume the POJO model was downloaded to the "Downloads" folder.</li>
</ol>

<h3>Step 3 (in a *new* terminal window - H2O must still be running in the first terminal window): Download model pieces</h3>
<pre>
$ mkdir experiment
$ cd experiment
$ mv ~/Downloads/gbm_pojo_test.java .
$ curl http://localhost:54321/3/h2o-genmodel.jar > h2o-genmodel.jar
</pre>

<h3>Step 4 (in terminal window 2): Create the main program</h3>
Create a new file called <em>main.java</em> ( `vim main.java`) with the following contents:

<pre>
{@code
import java.io.*;
import hex.genmodel.easy.RowData;
import hex.genmodel.easy.EasyPredictModelWrapper;
import hex.genmodel.easy.prediction.*;

public class main {
  private static String modelClassName = "gbm_pojo_test";

  public static void main(String[] args) throws Exception {
    hex.genmodel.GenModel rawModel;
    rawModel = (hex.genmodel.GenModel) Class.forName(modelClassName).newInstance();
    EasyPredictModelWrapper model = new EasyPredictModelWrapper(rawModel);

    RowData row = new RowData();
    row.put("Year", "1987");
    row.put("Month", "10");
    row.put("DayofMonth", "14");
    row.put("DayOfWeek", "3");
    row.put("CRSDepTime", "730");
    row.put("UniqueCarrier", "PS");
    row.put("Origin", "SAN");
    row.put("Dest", "SFO");

    BinomialModelPrediction p = model.predictBinomial(row);
    System.out.println("Label (aka prediction) is flight departure delayed: " + p.label);
    System.out.print("Class probabilities: ");
    for (int i = 0; i < p.classProbabilities.length; i++) {
      if (i > 0) {
        System.out.print(",");
      }
      System.out.print(p.classProbabilities[i]);
    }
    System.out.println("");
  }
}
}
</pre>

<h3>Step 5 (in terminal window 2): Compile and Run</h3>
<pre>
$ javac -cp h2o-genmodel.jar -J-Xmx2g -J-XX:MaxPermSize=128m gbm_pojo_test.java main.java
$ java -cp .:h2o-genmodel.jar main
</pre>

The following output displays:
<pre>
        Label (aka prediction) is flight departure delayed: YES
        Class probabilities: 0.4790490513429604,0.5209509486570396
</pre>

<h3><a href="doc-files/GBM_Airlines_Classification.pdf" target="_blank">Appendix: PDF of the Flow that built this model</a></h3>

<!-- ============================================================ -->
<!-- ============================================================ -->
<br>
<hr>
<br>

<a name="extracting"></a>
<h1><u>Extracting generated models from H2O</u></h1>
Generated models can be extracted from H2O in the following ways:

<h3>From the H2O Flow Web UI: </h3>
When viewing a model, click the "Download POJO" button at the top of the model cell
(refer to the example in the "Quick Start" section).

You can also preview the POJO inside Flow, but it will only show the first 1000
lines or so in the web browser, truncating large models.

<h3>From R:</h3>
The following code snippet represents an example of H2O building a model and downloading its
corresponding POJO from an R script:
<pre>
{@code
library(h2o)
h2o.init()
path = system.file("extdata", "prostate.csv", package = "h2o")
h2o_df = h2o.importFile(path)
h2o_df$CAPSULE = as.factor(h2o_df$CAPSULE)
model = h2o.glm(y = "CAPSULE",
                x = c("AGE", "RACE", "PSA", "GLEASON"),
                training_frame = h2o_df,
                family = "binomial")
h2o.download_pojo(model)
}
</pre>

<h3>From Python:</h3>
The following code snippet represents an example of H2O building a model and downloading its
corresponding POJO from a Python script:

<pre>
{@code
import h2o
h2o.init()
path = h2o.system_file("prostate.csv")
h2o_df = h2o.import_file(path)
h2o_df['CAPSULE'] = h2o_df['CAPSULE'].asfactor()
model = h2o.glm(y = "CAPSULE",
                x = ["AGE", "RACE", "PSA", "GLEASON"],
                training_frame = h2o_df,
                family = "binomial")
h2o.download_pojo(model)
}
</pre>

<h3>From Java:</h3>
TODO: provide pointer of doing this directly from Java

<h3>From Sparkling Water:</h3>
The following code snippet represents an example of H2O building a model and downloading its
corresponding POJO from a Sparkling water script:

<pre>
{@code
import org.apache.spark.h2o._
val h2oContext = H2OContext.getOrCreate(sc)

import h2oContext._
import org.apache.spark.examples.h2o._
import java.io.File
val dataFile = "examples/smalldata/allyears2k_headers.csv.gz"
val airlinesData = new H2OFrame(new File(dataFile))

import _root_.hex.tree.gbm.GBM
import _root_.hex.tree.gbm.GBMModel.GBMParameters
val gbmParams = new GBMParameters()
  gbmParams._train = airlinesData
  gbmParams._response_column = 'IsDepDelayed
  gbmParams._model_id = water.Key.make("model")
  gbmParams._ntrees = 5
  gbmParams._max_depth = 2

val gbm = new GBM(gbmParams)
val model = gbm.trainModel.get

import water._
import _root_.hex._
import java.net.URI
import water.serial.ObjectTreeBinarySerializer

def exportPOJOModel(model : Model[_, _,_], destination: URI): URI = {
    val destFile = new File(destination)
    val fos = new java.io.FileOutputStream(destFile)
    val writer = new model.JavaModelStreamWriter(false)
    try {
      writer.writeTo(fos)
    } finally {
      fos.close()
    }
    destination
}
exportPOJOModel(model, new File("./GbmModel.java").toURI)
}
</pre>

<!-- ============================================================ -->
<!-- ============================================================ -->
<br>
<hr>
<br>

<a name="usecases"></a>
<h1><u>Use cases</u></h1>
The following use cases are demonstrated with code examples:

<h3>Reading new data from a CSV file and predicting on it</h3>
The {@link hex.genmodel.tools.PredictCsv} class is used by the H2O test harness to make
predictions on new data points.

<h3>Getting a new observation from a JSON request and returning a prediction</h3>
See the <a href="https://github.com/h2oai/app-consumer-loan" target="_blank">Consumer loan application github repository</a>.

<h3>A user-defined-function called directly from hive</h3>
See the <a href="https://github.com/h2oai/h2o-world-2015-training" target="_blank">H2O World 2015 Training github repository</a>.

</body>
